Références · Édition du 14 novembre 2026
Webhooks sortants
Les webhooks notifient un système externe après un événement de l’organisation. Ils sont distincts du webhook Stripe entrant. Leur gestion exige un compte administrateur et le module Studio.
Configurer
Dans Studio, créer un webhook avec une URL publique HTTPS et les événements voulus. Le code limite à dix webhooks par organisation. Le secret complet n’est présenté qu’à la création. Tester l’adresse depuis l’action de test et consulter le dernier résultat ; supprimer le webhook pour arrêter ses livraisons suivantes.
| Événement | Déclencheur |
|---|---|
| document.sent | Document envoyé |
| document.paid | Facture soldée |
| client.created | Client créé |
| task.created | Tâche créée |
| task.done | Tâche terminée |
| member.created | Personne ajoutée |
Contrat de livraison
POST JSON contient event, data et created. En-têtes : Content-Type: application/json, X-Orgia-Event et X-Orgia-Signature. La signature a la forme t=horodatage,v1=empreinte, HMAC SHA-256 sur les octets de l’horodatage, un point et le corps brut. Le secret est celui de ce webhook.
Le destinataire doit vérifier la signature sur les octets reçus, refuser un horodatage trop ancien et rendre ses traitements idempotents. Aucun identifiant d’événement durable n’est ajouté par ce contrat.
Exemple de vérification côté destinataire
Cette fonction vérifie la signature ; l’intégration HTTP et le stockage d’anti-rejeu relèvent du système destinataire. Ne pas réencoder le JSON avant vérification.
import hashlib, hmac, time
def signature_valide(header, body, secret):
try:
fields = dict(part.split('=', 1) for part in header.split(','))
stamp = int(fields['t'])
if abs(time.time() - stamp) > 300:
return False
signed = str(stamp).encode() + b'.' + body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, fields['v1'])
except (ValueError, KeyError, TypeError):
return False
Limites opérationnelles
Le délai réseau est de cinq secondes. Les redirections et adresses internes sont refusées par défaut ; ne pas affaiblir ces protections pour une intégration publique. Les livraisons automatiques sont désactivées avec ORGIA_SCHEDULER=0. Le test manuel reste une action explicite.
L’envoi s’effectue dans un thread en arrière-plan ; le dernier statut est conservé. Il n’existe pas ici de file durable, de reprise garantie après redémarrage ni de stratégie automatique de nouvelles tentatives. Pour une synchronisation fiable, prévoir rapprochement périodique autorisé avec l’API et contrôle des événements manquants.